Copyright: ® 1995-1996 Tony Shaftel. All rights reserved.


Help Contents
Contents

VBNameChk

Introduction

Overview Of Operation

Name Check Tab

Name Standards Tab

Options Tab

Report Window

Report Grid Window

Exporting The Grid Contents

Pro Version

Registration And Support (Shareware version)

Acknowledgements

VBNameChk is a trademark of Shaftel Software.

Copyright 1995 Tony Shaftel. All rights reserved.


Introduction

VBNameChk is a tool for Visual Basic developers that helps manage source code naming conventions or standards.

Most programmers will agree that consistent naming of variables, constants, and other source objects is a good thing.  In the Windows world, the majority of programmers will also pay homage to some form of Hungarian prefix notation.  Getting a team of programmers to agree on a particular naming standard and then actually use it, however, may be a different story!

Well, if you can provide the standard, VBNameChk will help you stick to it.  You tell VBNameChk in detail what your prefix conventions are.  It will then read through the source code that makes up your VB project and report all violations of those standards, module by module, procedure by procedure.  Reports can be viewed interactively or printed.

The notation options provided by VBNameChk allow for a broad range of possible conventions.  If you use a prefix-based naming standard for your Visual Basic projects, chances are you can use VBNameChk to enforce it.

Comments, bug reports and suggestions for improving VBNameChk are appreciated.

Note: VBNameChk 2 adds the following features:

Support for VB4

Support for suffix notation (naming elements can be placed at the end of the name)

(VBNameChk is a trademark of Shaftel Software.  Windows and Visual Basic are trademarks of Microsoft Corporation.)


Overview
Overview Of Operation

Running A Name Check

Specifying The Naming Standards

Viewing Violation Reports


Running a Name Check

Project source files must be stored as text in order to be analyzed; those that are not will be indicated as such in the module's violation report and otherwise ignored.  In addition, the module report will indicate whether Option Explicit is declared for the module.  VBNameChk cannot guarantee a complete and accurate violation report if Option Explicit is not declared.  Finally, your source code must be syntactically correct or all bets are off.

1) On the Name Check tab, select a VBNameChk name standards file in the Name Standards combobox.  Two examples, SAMPLE1.NCK and SAMPLE2.NCK, are provided with the product.  You may create a new one from scratch, or modify a sample (step 2).

2) Modify (or enter for the first time) your naming standards, using the several panels of the Name Standards tab.  Use the Save or Save As... commands, store the completed standards in an NCK file for later reuse.

3) Select a Visual Basic project in the Project Makefile combobox.  This is the project you want to check against your naming standards.

4) Exclude any source modules from the Project Files listbox that you don't want to name-check.  Examples of these are vendor modules which do not conform to your naming standards.

5) Specify a directory where VBNameChk can place the violation reports, in the Report Directory combobox.

6) On the Options tab, specify whether you want the reports to include all names, or just violations.

7) Click the Do Name Check command button.  VBNameChk will scan the project and create a violation report for each source module in the Project Files listbox.

8) Double-click any entry in the Project Files listbox to view the violation report for that module.

See:	Name Check Tab

Name Standards Tab

Options Tab


Specifying The Naming Standards

The second of the two main tabs, Name Standards, is where you specify the naming conventions VBNameChk is to use.  The specification is divided into four groups, found on the Position and Types tab, Variables tab, Procs/Scopes/Consts tab and Order Of Prefix Elements tab (Pro version only).  See Name Standards Tab


Viewing Violation Reports

After the namescan has been run, double-clicking any module entry in the project list will bring up a report window containing the results for that module.  You can have several report windows open at once.  You may also use a single window to view any of the module reports--each report window has a combobox which contains the project list, so you can select the reports from there as well as from the main window.

See:	Report Window

Report Grid Window


Name Check Tab

This is the first tab you see when you start VBNameChk.  It contains the following elements:

Name Standards File Combobox

Common Command Buttons

Project Makefile Combobox

Project Files Listbox

Excluded Files Listbox

Report Directory Combobox

Do Name Check Command Button


Common Command Buttons

These buttons are always present on the name standards file panel, which appears on every tab.

•	Save

Save changes made to the currently open name standards file.

•	Save As

Brings up a File Save As Dialog so you can save the currently open name standards file under a new name.

•	Print Setup

This button opens a standard Print Setup dialog.

•	Print

This button prints the current name standards as they appear on the tabs.  (If you have altered but not saved them, this report will not match the contents of the file on disk.)

•	Help

Open the VBNameChk Help File at the Contents topic.

•	About

Open the About dialog box.

•	Exit

Quit the VBNameChk application.  Outstanding changes to the currently open name standards file will not be saved.  Options tab settings and the Name Standards File, Project Makefile and Report Directory combobox settings will be saved.


Name Standards File Combobox

You may define and save many name standards, each in its own file.  (By default, these are given the extension NCK.)  The combobox will contain the last several standards files used to do name checks.

The Browse button can be used to bring up a File Dialog to help locate and select a name standards file.


Project Makefile Combobox

This is where you select the project make file for the Visual Basic project you want to name-check.  The combobox will contain the last several projects you have name-checked.

The Browse button can be used to bring up a File Dialog to help locate and select a project make file.


Project Files Listbox

This listbox contains a subset of the source modules that make up the Visual Basic project you have selected using the Project Makefile Combobox.  By default, only modules with the following extensions are included: FRM, BAS, GBL and GLB (the last two are used by some developers to name VB modules which contain global declarations).

Project modules with other extensions will be found in the Excluded Files listbox to the left.  The reason for excluding them, at least initially, is that they are commonly vendor modules which support addin controls or libraries, and declared names in these modules are unlikely to follow your naming conventions.

You may use the Add, Add All and Remove buttons to shift modules between the Project Files listbox and the Excluded Files listbox.


Excluded Files Listbox

See:	Project Files Listbox


Report Directory Combobox

This is where you select the destination directory where VBNameChk should place violation reports.  The combobox will contain the last several directories used.


Do Name Check Command Button

This button initiates the name check.  The name standards contained in the file selected in the Name Standards File combobox are applied against the VB project selected in the Project Makefile combobox.  A violation report file for each module containing naming violations is written to the directory selected in the Report Directory combobox.  These report files have the same name as the source module, with the last character of the extension replaced by the character specified in the Report Extension Character field on the Options tab (the default is '@').


Name Standards Tab

This is the second main tab.  It is divided into four subtabs:

Position and Types Tab

Scopes, Consts, Procs Tab

Variables Tab

Order Of Prefix Elements Tab (Pro version only)

These tabs are described in the following sections.


Types Tab
Position and Types Tab

This tab contains:

•	Prefix Position

The two option buttons allow you to select whether you want your naming convention to be applied to the beginning (prefix) or end (suffix) of the identifiers found in your source code.

The Require Underscore checkbox, if checked, means you want the prefix or suffix to be separated from the rest of the identifier name by an underscore (e.g. gn_MyInt or MyInt_gn).

•	Types Listboxes

One lists the types that are built into VB; the other lists addin controls.  Each entry in the lists consists of a data, control or object type along with the prefix you want associated with that type.  You may add, modify and delete entries in either list.

VBNameChk now allows up to six prefixes to be defined for any single type.  For instance, in addition to the commonly used integer prefix 'n', you may now assign 'h' in order to accomodate handles (e.g. 'hWnd').

See:	Adding, Modifying And Deleting Types


Scopes, Consts, Procs Tab

The following naming elements are specified on this tab:

Scope Prefixes

Constant Prefixes

Procedure Prefixes


Variables Tab

The following naming elements are specified on this tab:

Instance Variables

Single Letter Integers

Miscellaneous Variable Prefixes


Order Of Prefix Elements Tab
Order of Prefix Elements Tab (Pro version only)

In the Pro version, you can specify the order in which various naming elements appear in the prefix.  For instance, in the variable name ganMyInt (global array of integers) the order of the prefix elements is scope-array-datatype.

•	Variable Prefix Order

Depending on what you specify on other tabs, the name prefix for a variable can have up to four elements: scope, variable, array and datatype.  Using the mouse, drag the blue tablets into the order these elements should appear in.

•	Procedure Prefix Order

The name prefix for a sub or function can have up to three elements: scope, proctype (sub or function) and return type (for functions).  Using the mouse, drag the green tablets into the order these elements should appear in.

•	Procedure Argument Prefix Order

The name prefix for a procedure argument can have up to three elements: procarg, array and datatype.  Using the mouse, drag the yellow tablets into the order these elements should appear in.

To the right of each tablet set is an example of how a name of that kind will be prefixed according to your naming standard and the order you have selected.  This example is adjusted as you rearrange the tablets.

In the shareware version, the order of prefix elements is fixed as pictured in the tablets above.


Scope Prefixes

Arguably the most useful prefix after the datatype itself.  You may specify a prefix for variables of local, module and global scope.  The letters 'l', 'm' and 'g' suggest themselves, though many programmers don't use a local prefix.  Since some like to add an underscore, this prefix element may be one or two characters long.


Constant Prefixes

•	Numeric

This is a one or two character prefix for named numeric constants.  If you want one, 'N' works.  You probably want to capitalize it if your naming convention is to capitalize named constants.

•	String

This is a one or two character prefix for named string constants.  'S' is a good one.

•	Use Scope Prefix

You can specify whether you want your scope prefix elements to appear in the prefix of named constants.

•	Adjust Scope Prefix

If you do specify the use of scope prefixes for named constants, you can specify whether they should be upper-case, lower-case, or just As-Is (don't care).  Constants are commonly upper-cased, while scope prefixes are commonly lower-cased.  Using this option, you should be able to work it all out the way you want it.


Procedure Prefixes

•	Sub

You may specify a prefix for Sub procedure names.  Up to six characters may be used.

•	Function

You may specify a prefix for Function procedure names.  Up to six characters may be used.

•	Public Proc

You may specify a one or two character prefix for all public (global-scope) procedures.

•	Private Proc

You may specify a one  or twocharacter prefix for all private (module-scope) procedures..

•	Argument

You may specify a single character prefix for procedure arguments.  (Note that VBNameChk will not report Event Procedure Argument names as violations, since they are determined by the vendor of the control.)

•	Function Return

You may specify whether you want function names to include the datatype prefix that corresponds to the function return type.  For example, if a function returns an Integer and your Integer prefix is 'n', then 'n' would be part of the prefix for that function's name.


Instance Variables

The term 'instance' is used loosely here to refer to variables declared from forms, mdiforms, mdichild forms, user defined types, and VB4 classes.  The distinction is between the 'class' and the 'instance'.  This is obvious in the case of classes (VB4) and user defined types, from which variables must be declared or they don't serve much purpose.  Not all VB programmers, however, routinely declare instances of forms.  As you know, a new type or 'class' is created when you create a form module--the Name property of the form identifies the class, and you may declare new object variables of this form class.

VBNameChk gives you the opportunity to distinguish between the class and the instance in your naming convention.  The class prefix is specified in the entry in the Built-In Types listbox--e.g. specifying the prefix 'frm' for the Form type means the Name property of every form should begin with 'frm'.  You may specify a different prefix for instances of forms on the Instance panel of the Variables tab:

Example:

The prefix for any UDT is specified as 'udt'.

The prefix for UDT instances is 'typ'.

A UDT is declared as udtMyRec.

Type udtMyRec

......

End Type

Dim typRec as udtMyRec

Example:

The prefix for any Form is specified as 'frm'.

The prefix for form instances is 'vfrm'.

A form module exists, and its Name property is 'frmMainWin'.

Dim vfrmNewMainWin as frmMainWin

Set vfrmNewMainWin = new frmMainWin


Single Letter Integers

Let's face it.  Most programmers, particularly the C kind, will not happily give up their single letter loop iterators.  The wise project manager will not expect them to cheerfully switch from

for i = 0 to lstBob.ListCount - 1

to something like

for nI = 0 to lstBob.ListCount - 1

So a little compromise is in order.  In this panel, you specify which letters may be used to declare single-letter Integer and Long variables.  For instance, if you think nobody should ever nest a loop more than three deep, allow i, j and k for integers.  If blood is being shed over the naming convention and it's time to give a little, lengthen the list and allow some single-letter longs, too.


Miscellaneous Variable Prefixes

•	Array Prefix

You may specify a single letter that should be used in the prefix of an array variable.  The letter 'a' is a good candidate.

•	Variable Prefix

You may specify a single letter that should be used in the prefix of any variable--e.g. gvnMyInt (global variable of type Integer).  Some shops do it.


Options Tab

•	Show Violations Only

If this box is checked, only names which violate the name standards will be listed in the module reports.  If this box is left unchecked, all names will be listed.

•	Report Extension Character

This character will be used to construct the name of each violation report file.  It replaces the last character of the source module filename extension (e.g. if the character in this field is '@', MODULE.BAS would become MODULE BA@).  If the extension is fewer than 3 characters long, the '@' will be appended.

The options are automatically saved when the program exits in VBNMCHK.INI, not in the name standards (NCK) file.  Thus, they apply to all name checks without regard to which name standards file is currently loaded.


Adding Modifying And Deleting Types
Adding, Modifying And Deleting Types

Below both the Built-in and Add-in types listboxes on the Position and Types tab are New, Edit and Delete buttons which allow you to change the contents of the lists.

Clicking New or Edit opens a dialog box where you may define a new type or alter an existing one depending on the context.  The type prefix may be up to 6 characters long--it may also be left empty if you do not wish to enforce a prefix for that type.  The type name is the string by which the datatype, object or addin control is identified to Visual Basic.  This is easily determined by looking at an instance of the addin in the Properties Window--the type name assigned by the vendor is the right-hand string in the controlname combobox at the top of the window.

As an example, if you were using VideoSoft's Elastic control in your project (as VBNameChk does), the type name must be VideoSoftElastic; the prefix would be vse, ela or some other of your choosing.

See:	TypesTab


Report Window

This is where you view the results of a name check.  VBNameChk creates a violation report file for each source module listed in the Project Files Listbox.  If you double-click on the module in the listbox, the violation report will be displayed in a Report Window.  You may simultaneously display several reports at once, each in its own window.  Or, you may view reports one at a time in a single window.

The Pro version also allows you to view name and violation information in a filterable, user-manipulatable grid.

The window has the following elements:

•	Project Files Combobox

The contents of the main Project Files Combobox are reproduced in this combobox at the top left of the Report Window, to make it easy to select the report for any module.

•	Print Setup

This button opens a standard Print Setup dialog.

•	Print

This button opens a dialog which offers the choice of printing the currently displayed report, or all reports.

•	Close

This button closes the Report Window.

•	Report

The report itself is displayed in the scrollable textbox.  Each module report begins with some information describing the module.  After that, names declared in the module are listed by section: Declaration section first, followed by procedures.

Names in violation will be indicated by two asterisks on the left plus the correct prefix according to the name standards defined on the Name Standards panels.  Undefined objects such as third-party controls which have not been entered in the Add-in Types list will be flagged with a question mark.

Names of unknown type--most likely controls from a third-party vendor which have not been listed in the Add-in List--are indicated by two asterisks and a question mark.

Depending on the option selected, either all names will be listed or just those in violation.  Note that Event Procedure Argument names will not be flagged as violations, since these names are determined by a vendor.

See:	Project Files Listbox

Report Directory Combobox

Options Tab

Report Grid Window


Report Grid Window

In the Pro Version, the results of a name check can also be viewed in a user-configurable grid, one row per name.  The rows can filtered and sorted for your convenience.  Columns can be repositioned (by left-clicking and dragging the column header) and hidden (by dragging the right border of the column over to the left border).  The grid also supports "splits"--dragging to the right the small black rectangle at the lower left corner of the grid creates another grid which can be scrolled independently of the first.

The narrow columns need their headers explained.  An asterisk in the "V" column indicates a violation of the naming standard.  An asterisk in the "A" column indicates an array.  One in the "Ev" column indicates an event procedure.  The "Scp" column indicates the scope of the name--local, module or global.

The window has the following elements and features:

•	Module Combobox

The contents of the main Project Files Combobox are reproduced in this combobox at the top left of the Grid Window.  Selecting a module causes the grid to display only names declared in that module.  The first item in the combobox, "[All]", causes all names in the project to be listed; this is the default.

•	Name Filter Textbox

Any text entered into this textbox acts as a filter.  Only names beginning with the characters entered will be displayed in the grid.  Tabbing out or hitting Enter activates the filter.  Clearing the textbox removes the filter.

•	Types Combobox

This combobox lists all the data types found on the Position and Types Tab of the main form.  Selecting any type causes the grid to display only names of that type.  The first item, "[All]" is the default.

The three filters can be used separately or in combination with one another.

•	Column Sorting

To sort the grid on a particular column, right-click on the column header.  The sort columns are "remembered"; that is, if you sort on a second column, the grid will be ordered with the second column as the major sort and the prior column as the secondary sort.  The grid will sort on the last three columns selected in this fashion.

To clear the sorts, click the Restore/Clear Sort Columns menu.  This will restore the default order of the grid rows, which is the order of their physical appearance in the source modules.

•	Hiding and Showing Columns

Columns which have been hidden (by dragging the right border of the column over to the left border) may be made visible again by clicking the Restore/Show Hidden Columns menu.

See:	Report Window


Exporting The Grid Contents

Although VBNameChk provides two ways to view the results of a name scan--the modules reports and the Grid Window--you may want to customize the results with your own report writing tool.  To facilitate this, you can export the contents of the grid in one of two formats, comma-delimited or fixed-width.

To export, use the File/Export menu on the Grid Window.  You will be prompted to select one of the formats and specify the name and location of the output file.

The character width of the fields in the output records using the fixed-width option are:

Violation Indicator	1

Identifier Name	40

Scope Indicator	2

Object Type	40

Data Type	40

Array Indicator	1

Prefix	12

Procedure Name	40

Event Proc Indicator	1

Module Name	40


Pro Version

The professional version of VBNMCHK is called VBNMCHK Pro.  It offers the following added capabilities:

•	Prefix Ordering

The order of the different elements of the prefix (scope, array, datatype, etc) can be specified.

See Order Of Prefix Elements Tab.

•	Report Grid

In addition to the Report Window, information on all the names extracted from the source code is presented in grid format, where it can be filtered and sorted to more conveniently display items of interest.  The contents of the grid window may also be exported for use in other reporting tools.  See Report Grid Window

•	Suffixes and Underscores

The Pro version allows you to specify that the naming convention elements should be placed at the end of names, instead of the usual prefix.  You may also specify that an underscore should separate the prefix or suffix from the rest of the name.


Acknowledgements

I would like to acknowledge Jon Bek, whose kind words and encouragement were far more appreciated than deserved.  Also John Beverstock, who was charged with the unenviable task of defining the corporate VB naming standards and getting them used.  Since I was in the department, I had no choice--and ended up a better programmer.

VBNameChk uses a lexical analyzer generated using FLEX, a LEX variant.  You can't use or read about FLEX without coming across grateful mention of Vern Paxson, one of the FLEX developers and "still the flex guy"--as he put it in his response to an email question I launched, without much hope of success, out into the Internet ether.  Lo and behold, there he was.


Registering VBNameChk
Registering VBNameChk (Shareware version)

License Agreement

Registration And Support

Order Form


License Agreement

Thank you for using VBNameChk--we hope you find it valuable and want to add it to your VB toolkit.  VBNameChk is distributed in two versions: a shareware version and a Pro version.  The shareware version is provided at no charge to the user for evaluation.  Feel free to share it with your friends, but do not give it away altered or as part of another system.  The shareware version of VBNameChk is distributed as VBNCKnnn.ZIP (where nnn is the version number).  If you distribute VBNameChk to friends, associates, or to a computer bulletin board system (BBS), please distribute the ZIP file rather than the individual files for VBNameChk.  The zip file does not contain the required Visual Basic runtime DLL.  This module is available on many BBS's including Compuserve, and virtually all users of VBNameChk will already have it anyway.

VBNMCHK Pro, which contains additional features, is not a shareware product and may not be copied except for backup purposes.

REGISTRATION

If you as an individual find VBNameChk useful and continue to use it after a reasonable trial period, please make a registration payment (see Registration Fee) to Shaftel Software.  The registration fee will license one copy for use on any one computer at any one time.  For any version of VBNameChk, if used on a local area network, one copy must be purchased for each computer that will be using VBNameChk.  Site or enterprise-wide license arrangements must be negotiated in advance of use.  Use on a wide area network is strictly prohibited without such an arrangement.

Business, government, institutional and other organizational users of VBNameChk must register and pay for their copies of the program within 30 days of first use or their license is withdrawn.

The registration fee may be applied at a later date toward the purchase of the Pro version.

DISCLAIMER OF WARRANTY

THIS SOFTWARE AND MANUAL ARE SOLD "AS IS" AND WITHOUT WARRANTIES AS TO PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER EXPRESSED OR IMPLIED.  BECAUSE OF THE VARIOUS HARDWARE AND SOFTWARE ENVIRONMENTS INTO WHICH THIS PROGRAM MAY BE PUT, NO WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED.  GOOD DATA PROCESSING PROCEDURE DICTATES THAT ANY PROGRAM BE THOROUGHLY TESTED WITH NON-CRITICAL DATA BEFORE RELYING ON IT.  THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM.  ANY LIABILITY OF THE SELLER WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE.

DISTRIBUTORS

Anyone distributing the shareware version of VBNameChk for any kind of remuneration must first contact Shaftel Software for authorization, with details including price to be charged.  This authorization will be automatically granted to distributors recognized by the Association of Shareware Professionals (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering VBNameChk immediately.  (However Shaftel Software must still be advised so that the distributor can be kept up-to-date with the latest version of VBNameChk.)

Distributor advertisements, catalogs, etc must explain the shareware concept, and state that this program is not free, but is copyrighted software that is provided to allow the user to evaluate it before paying.


Registration Fee
Registration And Support

The registration fee for a single shareware license is $25.00.  The price for VBNMCHK Pro, which contains certain additional features and is not distributed as shareware, is $69.00 per license.  California customers, please add sales tax.  Please add $3.00 shipping and handling outside North America.

If you as an individual find VBNameChk useful and continue to use it after a reasonable trial period, please pay for value received and register.

Business, government, institutional and other organizational users of VBNameChk must register and pay for their copies of the program within 30 days of first use or their license is withdrawn.

The fee will license one copy for use on a single computer.  For full licensing details including network arrangements, please see License Agreement.

Payment must be made by check or credit card (VISA, Mastercard, American Express or Discover) in U.S. dollars at time of order unless prior arrangements are made.

PAYMENT BY CHECK

If payment is by check, send your order to:

Shaftel Software

P.O. Box 12485

La Crescenta, CA 91224-5485

PAYMENT BY CREDIT CARD

If payment is by credit card, order from Public (software) Library by calling 800-2424-PsL or 713-524-6394 or by FAX to 713-524-6398 or by CIS Email to 71355,470. You can also mail credit card orders to PsL at P.O.Box 35705, Houston, TX 77235-5705.

The above numbers are for orders only.  PsL does not handle inquiries or provide technical support.

Any questions about the status of the shipment of the order, refunds, registration options, product details, technical support, volume discounts, dealer pricing, site licenses, etc, must be directed to Shaftel Software as described below.

REGISTERING ON COMPUSERVE

GO SWREG.  Registration id 8315.

SUPPORT

Shaftel Software can be contacted by fax for support or with questions.  The number is (818) 957-7992.  We can also be reached on Compuserve at 72540,1462, or via the Internet at 72540.1462@compuserve.com.  Or, you may reach us by mail at the above address.

Comments, bug reports and suggestions for improving VBNameChk are always welcome.


Order Form
VBNameChk Order Form

Name:	____________________________________________________

Company:	____________________________________________________

Address:	____________________________________________________

____________________________________________________

City:	_______________________ State: ______ Zip: _____________

Country	:	___________________

Date:	___________________

_____	Shareware copies @ 25.00	$__________

Sales Tax (CA)	$__________

_____	VBNMCHK Pro copies @ 69.00	$__________

Sales Tax (CA)	$__________

S&H  outside N. America $3	$__________

Check Total (U.S. dollars)	$__________

    ( ) 3.5" disk   ( ) 5.25" disk

First acquired or learned about VBNameChk from:

    ( ) Friend	( ) Coworker	( ) Catalog	( )BBS:___________________

    ( ) Other__________________________________________________________

5-2.0

    Send to:	Shaftel Software

P.O. Box 12485

La Crescenta, CA 91224-5485